Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / Pdev.man < prev next >

Wrap

Text File | 1990-08-27 | 29.4 KB | 663 lines

Pdev C Library Procedures Pdev _________________________________________________________________ NNAAMMEE Pdev_Open, Pdev_Close, Pdev_SetDefaultHandler, Pdev_SetStreamHandler, Pdev_EnumStreams - Package for ser- vicing pseudo-devices. SSYYNNOOPPSSIISS ##iinncclluuddee <<ppddeevv..hh>> Pdev_Token PPddeevv__OOppeenn(_n_a_m_e, _r_e_a_l_N_a_m_e_P_t_r, _r_e_q_B_u_f_S_i_z_e, _r_e_a_d_B_u_f_S_i_z_e, _s_e_r_- _v_i_c_e, _c_l_i_e_n_t_D_a_t_a) void PPddeevv__CClloossee(_p_d_e_v_T_o_k_e_n) int PPddeevv__GGeettSSttrreeaammIIDD(_p_d_e_v_T_o_k_e_n) int (* PPddeevv__SSeettDDeeffaauullttHHaannddlleerr(_p_d_e_v_T_o_k_e_n, _o_p_e_r_a_t_i_o_n, _h_a_n_d_l_e_r))() int (* PPddeevv__SSeettSSttrreeaammHHaannddlleerr(_s_t_r_e_a_m_P_t_r, _o_p_e_r_a_t_i_o_n, _h_a_n_d_l_e_r))() int PPddeevv__EEnnuummSSttrreeaammss(_p_d_e_v_T_o_k_e_n, _f_u_n_c, _c_l_i_e_n_t_D_a_t_a) AARRGGUUMMEENNTTSS char *_n_a_m_e (in) Name of file to use for pseudo-device. char **_r_e_a_l_N_a_m_e_P_t_r (out) Where to store pointer to actual pseudo-device file name, or NULL if _n_a_m_e is to be the complete name of pseudo-device file. int _r_e_q_B_u_f_S_i_z_e (in) The preferred size for request buffers. int _r_e_a_d_B_u_f_S_i_z_e (in) The size for a read buffer. Zero means no read buffering. Pdev_CallBacks *_s_e_r_v_i_c_e (in) A set of service call-back pro- cedures. ClientData _c_l_i_e_n_t_D_a_t_a (in) Private user- defined data field. Pdev_Token _p_d_e_v_T_o_k_e_n (in) Token for the Sprite v.1.0 Printed: August 27, 1990 1 Pdev C Library Procedures Pdev pseudo-device returned from PPddeevv__OOppeenn. Pdev_Stream *_s_t_r_e_a_m_P_t_r (in) Handle for a stream to the pseudo- device. int _o_p_e_r_a_t_i_o_n (in) PPDDEEVV__OOPPEENN, PPDDEEVV__CCLLOOSSEE, PPDDEEVV__RREEAADD, PPDDEEVV__WWRRIITTEE, PPDDEEVV__IIOOCCTTLL, PPDDEEVV__SSEETT__AATTTTRR, PPDDEEVV__GGEETT__AATTTTRR. int (*_h_a_n_d_l_e_r)() (in) Service call-back procedure. int (*_f_u_n_c)() (in) A procedure applied to each stream to the pseudo-device. _________________________________________________________________ PPddeevv__OOppeenn PPddeevv__OOppeenn creates a pseudo-device and installs a set of ser- vice procedures for it. The pseudo-device can subsequently be opened by any number of regular (client) processes, and the service call-backs are made each time a client process makes a file system operation on the pseudo-device. Thus the service call-backs implement the standard file system operations for the pseudo-device while the Pdev package manages the interface between the kernel and the server pro- cess. There are two ways that PPddeevv__OOppeenn can pick the name of the file to use for the pseudo-device. If _r_e_a_l_N_a_m_e_P_t_r is NULL, then PPddeevv__OOppeenn uses _n_a_m_e as the name. If _r_e_a_l_N_a_m_e_P_t_r isn't NULL, then PPddeevv__OOppeenn will generate a file name of the form _h_o_s_t_D_i_r//_n_a_m_e_X_X, where _h_o_s_t_D_i_r is the name of a standard host-specific directory, _n_a_m_e is the parameter to this pro- cedure, and _X_X is a decimal number generated by PPddeevv__OOppeenn. PPddeevv__OOppeenn tries numbers up from 1 until it finds one that works. The name of the successful pseudo-device file is returned by storing a pointer to it at *_r_e_a_l_N_a_m_e_P_t_r; the storage for the name is dynamically allocated with mmaalllloocc and must eventually be freed by the caller. PPddeevv__OOppeenn returns an opaque token that is used in calls to PPddeevv__CClloossee, PPddeevv__SSeettDDeeffaauullttHHaannddlleerr, and PPddeevv__EEnnuummSSttrreeaammss. If a pseudo-device couldn't be opened, then NULL is returned and ppddeevv__EErrrroorrMMssgg contains a string describing the problem. Sprite v.1.0 Printed: August 27, 1990 2 Pdev C Library Procedures Pdev After a successful PPddeevv__OOppeenn call the Pdev package will set up a _s_e_r_v_i_c_e _s_t_r_e_a_m whenever a client process opens the pseudo-device. Each service stream is identified to the call-backs by a PPddeevv__SSttrreeaamm record. Thus the pseudo-device can be multiplexed over several clients with each client's request comming over a different service stream. However, forks and dups are not visible to the pseudo-device server, so more than one process might be using any particular ser- vice stream. The _r_e_q_B_u_f_S_i_z_e is used to configure a request buffer associ- ated with each service stream. This size determines how many request messages can be buffered before the kernel is forced to wait for them to be serviced. More than one request may be outstanding due to asynchronous writes, which are described below. A minimum size on the request buffer is enforced by the library, so zero can be passed in to get a default size (about 1 Kbyte). The _r_e_a_d_B_u_f_S_i_z_e is used to configure an optional read buffer associated with each service stream. If this size is non- zero it indicates that a read buffer will be used to satisfy client read requests instead of using the read service call-back. In this case the Pdev package will allocate a read buffer each time a service stream is created and pass the address of this buffer to the open call-back. After that it is up to the server process to manage the read buffer. See the device man page for ppddeevv for details. The _c_l_i_e_n_t_D_a_t_a parameter to PPddeevv__OOppeenn is passed to the open call-back as described below. It is meant to be used as a pointer back to some top-level state of the pseudo-device. The Pdev package uses the facilities of FFss__DDiissppaattcchh in order to keep track of the streams associated with the pseudo- device and ensure that Pdev is notified whenever those streams become readable. In order to use Pdev, you must also use FFss__DDiissppaattcchh. PPddeevv__CClloossee PPddeevv__CClloossee shuts down a pseudo-device, closing all the streams associated with it and releasing any resources allo- cated to the pseudo-device. As a side-effect the close call-back is made to any existing service streams. After this procedure returns, _p_d_e_v_T_o_k_e_n should never be used again. PPddeevv__GGeettSSttrreeaammIIDD PPddeevv__GGeettSSttrreeaammIIDD returns the identifier for the stream associated with the token returned by PPddeevv__OOppeenn. This may be used for stream-oriented calls such as ffssttaatt but should not be used as the argument to cclloossee (PPddeevv__CClloossee should be Sprite v.1.0 Printed: August 27, 1990 3 Pdev C Library Procedures Pdev used instead.) PPddeevv__EEnnuummSSttrreeaammss The PPddeevv__EEnnuummSSttrreeaammss procedure is used to apply a function to all the service streams to the pseudo-device. This enumeration procedure eliminates the need to keep track of each service stream. The _f_u_n_c argument is called on each service stream as follows: int (*func)(streamPtr, clientData) Pdev_Stream *streamPtr; ClientData clientData; Where _s_t_r_e_a_m_P_t_r identifies the service stream, and _c_l_i_e_n_t_- _D_a_t_a is what was passed to PPddeevv__EEnnuummSSttrreeaammss. _f_u_n_c should return zero to mean success, or a non-zero error status. In the case of an error PPddeevv__EEnnuummSSttrreeaammss stops its enumeration and returns the non-zero status. PPddeevv__SSeettDDeeffaauullttHHaannddlleerr PPddeevv__SSeettDDeeffaauullttHHaannddlleerr is used to set the call-back for individual pdev operations. It is not normally needed as you can define all the call-backs with PPddeevv__OOppeenn (or PPffss__OOppeennCCoonnnneeccttiioonn). The call-backs passed to PPddeevv__OOppeenn are inherited by each service stream that is created. Changing a call-back with PPddeevv__SSeettDDeeffaauullttHHaannddlleerr changes the call- back for all subsequently created service streams. It doesn't affect any service streams that are already esta- blished. This returns the old default call-back. PPddeevv__SSeettSSttrreeaammHHaannddlleerr PPddeevv__SSeettSSttrreeaammHHaannddlleerr is used to set a call-back for an already existing service stream. It returns the old call- back. SSEERRVVIICCEE PPRROOCCEEDDUURREESS The call-back service procedures are given to PPddeevv__OOppeenn (and PPffss__OOppeennCCoonnnneeccttiioonn) as a record of procedures: typedef struct { int (*open)(); /* PDEV_OPEN */ int (*read)(); /* PDEV_READ */ int (*write)(); /* PDEV_WRITE and PDEV_WRITE_ASYNC */ int (*ioctl)(); /* PDEV_IOCTL */ int (*close)(); /* PDEV_CLOSE */ int (*getAttr)(); /* PDEV_GET_ATTR */ int (*setAttr)(); /* PDEV_SET_ATTR */ } Pdev_CallBacks; Any of the record elements can be NULL to indicate that the operation should be handled by a default handler. The Sprite v.1.0 Printed: August 27, 1990 4 Pdev C Library Procedures Pdev _s_e_r_v_i_c_e parameter itself can also be NULL to indicate default handling for all operations. This is only useful during initial test. If a client makes an operation for which no service procedure is provided it is simply a no-op; it is not an error. The global variable ppddeevv__TTrraaccee can be set to a non-zero value to generate printfs to stderr when each service procedure (default or user-supplied) is invoked. Service procedures should return zero to mean successful completion, otherwise they should return an appropriate errno value. Additionally, the rreeaadd and wwrriittee procedures use EEWWOOUULLDDBBLLOOCCKK to indicate incomplete operations. This is described further below. Each service procedure also sets the current select state bits for the pseudo-device. The select bits are used in the kernel's implementation of sseelleecctt for pseudo-devices. They should be a bitwise or combination of FFSS__RREEAADDAABBLLEE, FFSS__WWRRIITTAABBLLEE, and FFSS__EEXXCCEEPPTTIIOONN. As well as setting this select state after each client operation, it may be set asynchronously with the IIOOCC__PPDDEEVV__RREEAADDYY iiooccttll command on the service stream. These same service procedures are used for pseudo-device connections into the pseudo-file-system. See PPffss__OOppeenn and PPffss__OOppeennCCoonnnneeccttiioonn. The ggeettAAttttrr and sseettAAttttrr call-backs are only made to pseudo-file-system servers. For regular pseudo-devices the kernel takes care of all attribute han- dling. ooppeenn int (*service->open)(clientData, streamPtr, readBuffer, flags, procID, hostID, uid, selectBitsPtr) ClientData clientData; /* Private data passed to Pdev_Open */ Pdev_Stream *streamPtr; /* Identifies stream to pseudo-device. */ char *readBuffer; /* Storage for optional read buffer */ int flags; /* Flags to the open system call. NOTE! * These are Sprite flags defined in <fs.h>, * not the Unix flags defined in <sys/file.h> */ int procID; /* ID of process opening the pseudo-device */ int hostID; /* Host where that process is executing */ int uid; /* User ID of that process */ int *selectBitsPtr; /* Return - the initial select state of the process */ When a client process makes an ooppeenn system call on the pseudo-device the Pdev library package invokes the ooppeenn ser- vice call-back to give the server a chance to refuse or accept the open by the client process. The return value of the open call-back is either 0 for success, or an appropri- ate errno value. Sprite v.1.0 Printed: August 27, 1990 5 Pdev C Library Procedures Pdev The ooppeenn call-back gets passed the _c_l_i_e_n_t_D_a_t_a that was given to the PPddeevv__OOppeenn procedure, and a new _s_t_r_e_a_m_P_t_r that is a handle on the service stream corresponding to the open by the client. _s_t_r_e_a_m_P_t_r is a pointer to a PPddeevv__SSttrreeaamm record that contains a cclliieennttDDaattaa field for use by the call-backs, and a ssttrreeaammIIDD field that is used in iiooccttll calls on the ser- vice stream. The possible iiooccttll calls are listed at the end of this man page. The _s_t_r_e_a_m_P_t_r gets passed to all the other call-backs, and is also passed to PPddeevv__SSeettSSttrreeaammHHaannddlleerr. The parameters also include the useFlags passed to the FFss__OOppeenn system call, and the user ID and Sprite hostID of the client process. (FFss__OOppeenn is the Sprite version of ooppeenn. The flag bits are different and are defined in <fs.h>. Flags passed to ooppeenn are mapped to the Sprite flag bits you'll get here.) If the _r_e_a_d_B_u_f_S_i_z_e parameter to PPddeevv__OOppeenn was non-zero then Pdev allocates _r_e_a_d_B_u_f_f_e_r and passes it to the open call-back. Thus there will be one read buffer for each service stream if the server is implementing read buffering. cclloossee int (*service->close)(streamPtr) Pdev_Stream *streamPtr; /* Identifies service stream */ This is called when a service stream is closed. This hap- pens either as a side effect of PPddeevv__CClloossee, or when the client has closed is last reference to the service stream. (Dups and forks are not visible to the pseudo-device server, so there is only one close per open system call by a client process.) rreeaadd int (*service->read)(streamPtr, readPtr, freeItPtr, selectBitsPtr, sigPtr) Pdev_Stream *streamPtr; /* Identifies service stream */ Pdev_RWParam *readPtr; /* Read parameter block */ Boolean *freeItPtr; /* Set to TRUE if buffer should be free'd */ int *selectBitsPtr; /* Return - select state of the pseudo-device */ Pdev_Signal *sigPtr; /* Return - signal to generate, if any */ The read service procedure is passed a record of type PPddeevv__RRWWPPaarraamm that indicates the lleennggtthh, ooffffsseett, and bbuuffffeerr for the read. The buffer is pre-allocated by the PPddeevv library. If the read service procedure wants to use a dif- ferent buffer it can change _r_e_a_d_P_t_r-->>bbuuffffeerr to reference its own storage. If this different storage area ought to be freed after the library completes the operation, then *_f_r_e_e_I_t_P_t_r should be set to a non-zero value. Sprite v.1.0 Printed: August 27, 1990 6 Pdev C Library Procedures Pdev The _r_e_a_d_P_t_r-->>lleennggtthh record field indicates how much data is requested, and it should be updated to reflect the amount of data actually returned. If there is no data available on the pseudo-device then the read call-back should return EEWWOOUULLDDBBLLOOCCKK and set _r_e_a_d_P_t_r-->>lleennggtthh to zero. This causes the kernel to block the client process until the select state of the pseudo-device is changed to indicate readabil- ity. If there are some bytes available the return value should be zero and _r_e_a_d_P_t_r-->>lleennggtthh set appropriately. If the read leaves no additional bytes available then the FFSS__RREEAADDAABBLLEE bit can be cleared from *_s_e_l_e_c_t_B_i_t_s_P_t_r in order to block the next read request. End-of-file is indicated to the client by a zero return code and a zero number of bytes returned. A signal can be generated in response to a read request by setting _s_i_g_P_t_r-->>ssiiggnnaall to a non-zero value. _s_i_g_P_t_r-->>ccooddee can also be set to modify the signal meaning. Data can be returned if a signal is generated. The client application's system call will complete, its signal handler, if any, will be invoked, and the system call will be retried. Note: If there is a read buffer associated with the service stream, which is indicated by a non-zero valued _r_e_a_d_B_u_f_S_i_z_e parameter to PPddeevv__OOppeenn, then this read call-back is never called. Instead the kernel takes data directly from the read buffer. The protocol for adding data to the read buffer is described in the ppddeevv device man page. wwrriittee int (*service->write)(streamPtr, async, writePtr, selectBitsPtr, sigPtr) Pdev_Stream *streamPtr; /* Identifies service stream */ int async; /* TRUE during an asynchronous write */ Pdev_RWParam *writePtr; /* Write parameter block */ int *selectBitsPtr; /* Return - select state of the pseudo-device */ Pdev_Signal *sigPtr; /* Return - signal to generate, if any */ The write service procedure is passed a parameter block that indicates the lleennggtthh, ooffffsseett, and bbuuffffeerr for the operation, plus various IDs of the application process. If _a_s_y_n_c is FFAALLSSEE (zero) then _w_r_i_t_e_P_t_r-->>lleennggtthh should be updated to reflect how much data was processed by the service pro- cedure. If _a_s_y_n_c is non-zero it indicates an asynchronous write and the service procedure must accept all of the data and the return value of _w_r_i_t_e_P_t_r-->>lleennggtthh is ignored. If the server cannot accept all of the data it must return EEWWOOUULLDDBBLLOOCCKK _a_n_d update _w_r_i_t_e_P_t_r-->>lleennggtthh to indicate just how much data it accepted. This return value causes the kernel to block the client process until the select state of the pseudo-device is changed to indicate writability. To Sprite v.1.0 Printed: August 27, 1990 7 Pdev C Library Procedures Pdev repeat, returning a short write count and a zero return code will cause the kernel to immediately issue another write request to complete the client's write operation. By also returning EEWWOOUULLDDBBLLOOCCKK the pseudo-device server forces the client process to wait until the pseudo-device becomes writ- able. A signal to the client application can be generated as a side effect by setting _s_i_g_P_t_r-->>ssiiggnnaall to a non-zero value. _s_i_g_P_t_r-->>ccooddee can be set to modify the signal. Data can be accepted by the write service procedure if a signal is gen- erated. The client application's write call will complete, its signal handler, if any, will be invoked, and the write call will be retried. iiooccttll int (*service->ioctl)(streamPtr, ioctlPtr, selectBitsPtr, sigPtr) Pdev_Stream *streamPtr; /* Set by open service procedure */ Pdev_IOCParam *ioctlPtr; /* I/O Control parameter block */ int *selectBitsPtr; /* Return - select state of pdev */ Pdev_Signal *sigPtr; /* Return - signal to generate, if any */ The ioctl service procedure takes a parameter block that specifies the ccoommmmaanndd, and two buffers, one containing input data (iinnBBuuffffeerr), and one for data returned to the client (oouuttBBuuffffeerr). The ioctl service has to set _i_o_c_t_l_P_t_r-- >>oouuttBBuuffSSiizzee to indicate how much data is being returned to the client process. The PPddeevv__IIOOCCPPaarraamm struct also contains various processIDs, and the ffoorrmmaatt of the host on which the client application is executing. The pseudo-device server can implement any _i_o_c_t_l_P_t_r-->>ccoommmmaanndd it wants. Generic commands are defined in <fs.h>, and other ranges of commands for particular devices and pseudo-devices are defined in header files in /sprite/src/lib/include/dev. The input and output data is not byteswapped by the operat- ing system. It is the server's responsibility to fix up the input and output buffers in the case that the client has a different byte order. The local byte order is defined as MMAACCHH__BBYYTTEE__OORRDDEERR by <machparam.h>, and the client's byte order and alignment are indicated by _i_o_c_t_l_P_t_r-->>ffoorrmmaatt. The FFmmtt__CCoonnvveerrtt library routine can be used to swap and align incomming and outgoing buffers. A signal to the client application can be generated as a side effect by setting _s_i_g_P_t_r-->>ssiiggnnaall to a non-zero value. _s_i_g_P_t_r-->>ccooddee can be set to modify the signal. ggeettAAttttrr int Sprite v.1.0 Printed: August 27, 1990 8 Pdev C Library Procedures Pdev GetAttrProc(streamPtr, attrPtr, selectBitsPtr) Pdev_Stream *streamPtr; /* Identifies service stream */ Fs_Attributes *attrPtr; /* Return - attributes */ int *selectBitsPtr; /* Return - select state of the pseudo-device */ This procedure is called to handle an fstat() call on a file in a pseudo-file system. The _s_t_r_e_a_m_P_t_r parameter identifies the open stream, and the server should fill in the attri- butes. This call-back is not made to regular pseudo-device servers, only to pseudo-file-system servers. sseettAAttttrr int SetAttrProc(streamPtr, flags, uid, gid, attrPtr, selectBitsPtr) Pdev_Stream *streamPtr; /* Identifies service stream */ int flags; /* Indicate what attributes to set */ int uid; /* Identifies user making the call */ int gid; /* Identifies group of process */ Fs_Attributes *attrPtr; /* Attributes to set as indicated by flags */ int *selectBitsPtr; /* Return - select state of the pseudo-device */ This procedure is called to set certain attributes of an open file in a pseudo-file system. The _s_t_r_e_a_m_P_t_r parameter identifies the open stream. The flags argument contains an or'd combinantion of FFSS__SSEETT__TTIIMMEESS, FFSS__SSEETT__MMOODDEE, FFSS__SSEETT__OOWWNNEERR, FFSS__SSEETT__FFIILLEE__TTYYPPEE, FFSS__SSEETT__DDEEVVIICCEE that indicate what attributes to set. The attribute values are contained in *_a_t_t_r_P_t_r. The _u_i_d and _g_i_d arguments identify the calling process. This call-back is not made to regular pseudo- device servers, only to pseudo-file-system servers. SSeerrvviiccee SSttrreeaamm IIooccttllss The pseudo-device server can make a few FFss__IIOOCCoonnttrrooll calls on its service streams. The details of the calling sequences is described in the device man page for pseduo- devices (pdev). The possible operations are: IOC_PDEV_READY Used to change the select state of the pseudo-device. The input buffer to Fs_IOControl should contain an or'd combination of FFSS__RREEAADDAABBLLEE, FFSS__WWRRIITTAABBLLEE, or FFSS__EEXXCCEEPPTTIIOONN. IOC_PDEV_SIGNAL_OWNER Used to send a signal to the owning process or process group of the pseudo-device. This is useful for imple- menting interrupt characters in tty emulators. No spe- cial permission is needed. IOC_PDEV_WRITE_BEHIND Used to set or unset asynchronous writing. Sprite v.1.0 Printed: August 27, 1990 9 Pdev C Library Procedures Pdev IOC_PDEV_BIG_WRITES Used to allow or disallow writes larger than the request buffer. IOC_PDEV_SET_PTRS Used to adjust pointers into the read buffer and the request buffer. Users of the Pdev package should only use this to adjust read buffer pointers. Leave the request buffer pointers equal to -1 so you don't mess up the managing of the request buffer. For example: status = Fs_IOControl(streamPtr->streamID, IOC_PDEV_READY, sizeof(int), &selectBits, 0, NULL); SSEEEE AALLSSOO pdev (devices), Pfs, Swap_Buffer KKEEYYWWOORRDDSS pseudo-device Sprite v.1.0 Printed: August 27, 1990 10